﻿////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
// <copyright>Copyright 2008-2011 Andreas Huber Doenni</copyright>
// Distributed under the GNU General Public License version 2 (GPLv2).
// See accompanying file License.txt or copy at http://phuse.codeplex.com/license.
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

namespace Phuse.Net
{
    using System;
    using System.IO;
    using System.Text;

    /// <summary>Represents the method that creates a <see cref="ResponseStream"/> object, through which the response to
    /// a stage command can be read.</summary>
    /// <param name="initialLineEncoding">The encoding to convert the bytes of the initial line into strings.</param>
    /// <param name="maxInitialLineWordCount">The length that the list returned by
    /// <see cref="ResponseStream.InitialLineWords">ResponseStream.InitialLineWords</see> will have. Since servers are
    /// allowed to add any text to the arguments mandated by the standard, this number should usually be 1 greater than
    /// the number of expected arguments. Moreover, every response starts with a response code, so this number must
    /// never be smaller than 2.</param>
    /// <param name="successResponseCodes">The response codes that are expected when the command succeeds. The element
    /// at index 0 of the <see cref="ResponseStream.InitialLineWords"/> property of the returned
    /// <see cref="ResponseStream"/> is guaranteed to be equal to one of these codes.</param>
    /// <returns>A <see cref="ResponseStream"/> object.</returns>
    /// <exception cref="ArgumentNullException"><paramref name="initialLineEncoding"/> and/or
    /// <paramref name="successResponseCodes"/> equal <c>null</c>.</exception>
    /// <exception cref="ArgumentOutOfRangeException"><paramref name="maxInitialLineWordCount"/> is smaller than 2.
    /// </exception>
    /// <exception cref="ClientBaseException">The response code received from the server indicates a known error
    /// condition, see the <see cref="CommandBase{T, U}.ThrowOnError"/> override for information on which
    /// <see cref="ClientBaseException"/> subtype is thrown for a given response code.</exception>
    /// <exception cref="IOException">A general I/O error occurred, see <see cref="Exception.InnerException"/>
    /// for more information.</exception>
    /// <exception cref="UnexpectedResponseException">The response received from the server was neither led by a
    /// response code indicating a known error (see <see cref="CommandBase{T, U}.ThrowOnError"/>) nor was it equal to
    /// one of the codes in <paramref name="successResponseCodes"/>.</exception>
    /// <remarks>
    /// <para>Calling an instance of <see cref="CreateCommandStreamCallback"/> or
    /// <see cref="CreateResponseStreamCallback"/> automatically calls <see cref="Stream.Dispose()"/> on the previously
    /// created stream (<see cref="CommandStream"/> or <see cref="ResponseStream"/>).</para>
    /// <para>A command <b>usually</b> does not handle exceptions thrown from this callback, but simply lets them
    /// propagate to the code issuing the command.</para>
    /// <para>See <see cref="ResponseStream"/> for more information.</para>
    /// </remarks>
    public delegate ResponseStream CreateResponseStreamCallback(
        Encoding initialLineEncoding, int maxInitialLineWordCount, params string[] successResponseCodes);
}
